Deploying Kanzi applications to iOS

Here you can find how you can deploy your Kanzi applications to iPhone, iPod, and iPad.

Changes between iOS versions have been incompatible in the past. The procedures documented were tested with the following software versions:

Mac OS X 10.7.5
Xcode 4.3.2
iOS SDK 5.1
Kanzi

Rightware cannot guarantee compatibility with other versions.

iOS libraries required for deploying Kanzi applications to iOS are included in Kanzi on request. Contact Rightware sales at sales@rightware.com to find out more.

Setup

Prerequisites

Before installing Kanzi iOS libraries, you need to set up a working iOS development environment. This can include:

Enrolling as an Apple Developer
Installing the Xcode IDE, including the iOS SDK
Creating the necessary provisioning profiles for your iOS device

For more information about setting up the environment for iOS development, see https://developer.apple.com.

You can test whether your environment is set up correctly by building the OpenGL Game example application provided with the iOS SDK. Once you have the OpenGL Game example running on your iOS device you can install the Kanzi iOS libraries.

Installing Kanzi iOS libraries

To install the Kanzi iOS libraries, copy the contents of the Kanzi iOS package to <KanziWorkspace>/Engine.

The Kanzi iOS package contains:

Kanzi debug and release libraries for iOS devices
Kanzi debug and release libraries for iOS Simulator
Example Xcode project

Workflow overview

This figure summarized the Kanzi workflow for iOS devices:

Kanzi Engine for iOS is provided as a set of libraries and associated header files. Kanzi application gains access to the functions provided by the Kanzi libraries by including the appropriate header files. You compile and link the application using the Xcode IDE. Kanzi Engine loads the Kanzi application content from a .kzb file you create by exporting your Kanzi Studio project before deploying it to an iOS device. See Using .kzb binaries.

You can use the example Xcode project provided in the Kanzi iOS package as a template for your iOS projects.

Running the example project on an iOS device

To run the example project on an iOS device:

Connect your iOS device to your computer using the USB cable provided with the device. Make sure the device is properly recognized by the operating system.
Double-click the kzb_player.xcodeproj file located under applications/kzb_player/configs/platforms/ios to open the example project into Xcode. In the top left corner of the Xcode window, select kzb_player as the scheme and your iOS device as the Destination.
Click the Run button in the top left corner of the Xcode window.
Xcode compiles, deploys, and starts running the example project on your iOS device.

Running the example project on the iOS Simulator

To run the example project on the iOS simulator, select the kzb_player_simulator as the Scheme and a suitable simulator Destination (for example, iPhone 5.1 Simulator).

Switching between the Debug and Release configurations

To switch between the Debug and Release configurations:

Open the Edit Scheme dialog from the Scheme drop-down menu.
In the Edit Scheme dialog select the Scheme and Destination for which you want to use the configuration, then select the Run action in the left pane and in the Info tab select either Debug or Release configuration.

Important settings

Project Build Settings

Header Search Paths

The Header Search Paths (HEADER_SEARCH_PATHS) setting lists all directories containing header files needed for compiling a Kanzi application.

Target Build Settings

Library Search Paths

The Library Search Paths (LIBRARY_SEARCH_PATHS) settings list the paths to the libraries referenced through the Other Linker Flags option in the Project Build Settings. The correct search paths depend on the Destination (Device/Simulator) as well as the Build Configuration (Debug/Release) you are using.

Target Build Phases

Link Binary With Libraries

The Link Binary With Libraries pane lists the frameworks needed by the application. Kanzi applications running on iOS required these frameworks:

GLKit.framework
OpenGLES.framework
QuartzCore.framework
UIKit.framework
Foundation.framework
CoreGraphics.framework

Copy Bundle Resources

The Copy Bundle Resources pane lists the resource files included in the final iOS application bundle. Kanzi applications require at least these:

binaries.cfg which lists the kzb files that your Kanzi application loads
At least one kzb file listed in the binaries.cfg

Troubleshooting

Error message	Solution
’application/kza_application.h’ file not found	Lexical or preprocessor issue. If a Kanzi header file is not found, the most probable cause is a wrong Header Search Path option in the Project Build Settings. Note that Target Build Settings can override Project Build Settings.
‘Directory not found’ or ‘Library not found’	Apple Mach-O Linker (ld) errors. If a Kanzi library is not found, check that Other Linker Flags and Library Search Paths in Project Build Settings or Target Build Settings are correct. Note that Target Build Settings can override Project Build Settings.
Error 10401: Failed to open resource file	Run-time Errors. The kzb file in the binaries.cfg does not match any of the kzb files exported from the Kanzi Studio. See Using .kzb binaries.
Wrong OpenGL/ES Configuration	Run-time Errors. Because of the design incompatibilities between Kanzi and iOS the OpenGL/ES configuration is not adjustable. Kanzi Engine libraries with a custom OpenGL/ES configuration are delivered separately. Contact Rightware sales at sales@rightware.com to find out more.